|
|
StyledLineBreak |
||||
| Header: | TextUtils.h | Carbon status: | Supported | |
Returns the proper location to break a line of text, taking into account script and language considerations, making use of tables in the string-manipulation ('itl2') resource in its computations.
StyledLineBreakCode StyledLineBreak (
Ptr textPtr,
SInt32 textLen,
SInt32 textStart,
SInt32 textEnd,
SInt32 flags,
Fixed *textWidth,
SInt32 *textOffset
);
A pointer to the beginning of a script run on the current line to be broken.
The number of bytes in the script run on the current line to be broken.
A byte offset to the beginning of a style run within the script run.
When used with unformatted text, textStart can be 0, and textEnd is identical to textLen. With styled text, the interval between textStart and textEnd specifies a style run. The interval between textPtr and textLen specifies a script run. Note that the style runs in StyledLineBreak must be traversed in memory order, not in display order.
A byte offset to the end of the style run within the script run.
Reserved for future expansion; must be 0.
A pointer to the maximum length of the displayed line in pixels. StyledLineBreak decrements this value for its own use. You are responsible for setting it before your first call to StyledLineBreak for a line.
StyledLineBreak automatically decrements the textWidth variable by the width of the style run for use on the next call. You need to set the value of textWidth before calling it to process a line.
A pointer to the text offset value, which must be nonzero on your first call to StyledLineBreak for a line, and zero for subsequent calls to StyledLineBreak for that line. This value allows StyledLineBreak to differentiate between the first and subsequent calls, which is important when a long word is found (as described below).
The textOffset parameter must be nonzero for the first call on a line and zero for each call to the function on the line. This allows StyledLineBreak to act differently when a long word is encountered: if the word is in the first style run on the line, StyledLineBreak breaks the line on a character boundary within the word; if the word is in a subsequent style run on the line, StyledLineBreak breaks the line before the start of the word.
On output, textOffset is the count of bytes from textPtr to the location in the text string where the line break is to occur. When StyledLineBreak finds a line break, it sets the value of textOffset to the count of bytes that can be displayed starting at textPtr.
When StyledLineBreak is called for the second or subsequent style runs within a script run, the textOffset value at exit may be less than the textStart parameter (that is, it may specify a line break before the current style run).
Indicates whether the function broke on a word boundary or a character boundary, or if the width extended beyond the edge of the text.
StyledLineBreak breaks the line on a word boundary if possible and allows for multiscript runs and style runs on a single line.
Use the StyledLineBreak function when you are laying out lines in an environment that may include text from multiple scripts. To use this function, you need to understand how QuickDraw draws text.
You can only use the StyledLineBreak function when you have organized your text in script runs and style runs within each script run. This type of text organization is used by most text-processing applications that allow for multiscript text. Use this function when you are displaying text in a screen area to determine the best place to break each displayed line.
What you do is iterate through your text, a script run at a time starting from the first character past the end of the previous line. Use StyledLineBreak to check each style run in the script run (in memory order) until the function determines that it has arrived at a line break. As you loop through each style run, before calling StyledLineBreak, you must set the text values in the graphics port structure that are used by QuickDraw to measure the text. These include the font, font size, and font style of the style run.
If the current style run is included in a contiguous sequence of other style runs of the same script, then textPtr should point to the start of the first style run of the same script on the line, and textLen should include the last style run of the same script on the line. This is because word boundaries can extend across style runs, but not across script runs.
Although the offsets are in long integer values and the widths are in fixed values for future extensions, in the current version the long integer values are restricted to the integer range, and only the integer portion of the widths is used.
StyledLineBreak always chooses a line break for the last style run on the line in memory order as if all whitespace in that style run would be stripped. The VisibleLength function, which is a QuickDraw function used to eliminate trailing spaces from a style run before drawing it, can be called for the style run that is at the display end of a line. This leads to a potential conflict when both functions are used with mixed-directional text: if the end of a line in memory order actually occurs in the middle of the displayed line, StyledLineBreak assumes that the whitespace is stripped from that run, but VisibleLength does not strip the characters.
Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.
© 2000 Apple Computer, Inc. (Last Updated 6/30/2000)